home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / manual-p / vh-man2h.000 / vh-man2h / vh-man2html-1.3 / README < prev    next >
Text File  |  1996-05-04  |  12KB  |  287 lines
  1. Caldera/Redhat oriented front ends to man2html
  2. ----------------------------------------------
  3. Michael Hamilton <michael@actrix.gen.nz>
  4. http://www.actrix.gen.nz/users/michael
  5.  
  6. Translate man pages to html from tbl/nroff source.
  7.  
  8. New in version 1.3:
  9.   - Tested/fixed bug with serving pages to remote UNIX hosts.
  10.   - Added man pages for man2html(8) and netscape-man(1).
  11.   - Renamed from man2html-linux to vh-man2html to avoid confusion with the
  12.     numerous man2html's out there (most of the others work from nroff output).
  13.     Also it is not really Linux specific - with minimal tailoring it could 
  14.     work on any UNIX box that uses source based man pages.
  15.  
  16.     vh = Richard Verhoeven's Man2html as modified and packaged up by Michael
  17.     Hamilton.
  18.  
  19. New in version 1.2:
  20.  
  21.   - I've enhanced man2hmtl.c so that it can format BSD mandoc man pages.
  22.     This means it can now cope with all the Caldera/Redhat man pages
  23.     (eg telnet, ftp, and lpr are now converted correctly).
  24.   - Added /usr/bin/netscape-man script which performs like the man command
  25.     but talks to a live (already running) netscape to present pages, e.g.
  26.        netscape-man lpr         - netscape pops up lpr man page.
  27.        netscape-man 8 sendmail  - pops up sendmail (8) man page.
  28.        netscape-man 7 into      - pops up name+description index for sec 7.
  29.        netscape-man 5           - pops up name-only index for sec 5.
  30.        netscape-man -k pine     - pops up a glimpse text search for pine.
  31.     You can alias man to netscape-man in your shell .profile or .cshrc.
  32.   - I revisited the awk scripts, mansec index creation time has been 
  33.     reduced considerably on larger sections.  From 25 seconds down to
  34.     10 on my 486DX2/66 for Section 3 with about 950 man pages.
  35.   - Manwhatis index creation time has also been reduced.  From 1 minute 
  36.     down to 8 seconds for the same section.
  37.   - Temporary files are now suffixed with the process id in case two or
  38.     more people simultaneously invoke them.
  39.   - The scripts now do safer (mv based) updates of the cache files to prevent
  40.     errors due to more than one person simultaneously updating them.
  41.   - Support for makewhatis programs that produce full section numbers
  42.     e.g. they produce xterm(1x) rather than xterm(1).  See the end of
  43.     this file for a patch to makewhatis from man-1.4g.
  44.   - Fixed core dumping on Gawk.1 page.
  45.   - Fixed malloc bug(s) (eg don't try the lynx.1 page with version 1.1 - 
  46.     corrupt memory = infinite loop).  Did this by def'ing free to do
  47.     nothing - ie leak until exit() - it doesn't run long, and doesn't 
  48.     malloc much anyway - trust me.
  49.  
  50. New in version 1.1:  
  51.   - Full text search via glimpse.
  52.   - All scripts now generate valid, stylistically correct, html according to 
  53.     weblint (see http://www.khoros.unm.edu/staff/neilb/weblint.html).
  54.   - Consistent titles and headers.
  55.   - More compact Main Contents page.
  56.  
  57.  
  58. QUICK START INSTRUCTIONS
  59. ------------------------
  60.  
  61. To use these cgi scripts all you have to do is install the rpm and
  62. then point your web browser at
  63.  
  64.         http://localhost/cgi-bin/man2html 
  65.  
  66. You can either save this location as a bookmark or use an editor to
  67. insert the following lines into an appropriate place in
  68. /usr/doc/HTML/calderadoc/caldera.html
  69.  
  70.    <H3><A HREF="http://localhost/cgi-bin/man2html"><IMG SRC="book2.gif">
  71.    Caldera Linux Manual Pages</A></H3>
  72.  
  73. For some of the indexes to work you must generate the necessary
  74. databases...
  75.  
  76. My manwhatis CGI script uses the /usr/man/whatis file to build
  77. a man page index.  Caldera 1.0 normally builds the /usr/man/whatis every
  78. morning at 3:21am.  If this job has never been run (perhaps because
  79. you turn your machine off at night), you can build it by becoming the
  80. root user and entering:
  81.  
  82.    /usr/sbin/makewhatis /usr/man /usr/X11R6/man /usr/local/man
  83.  
  84. WARNING: makewhatis in Caldera 1.0 takes about 30 minutes on my
  85. 486DX66.  I have a modified version of makewhatis so that it does
  86. exactly the same job in only 1.5 minutes. My modified version is now
  87. available as part of man-1.4g.tar.gz:
  88.  
  89.    ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers
  90.  
  91. To use the Glimpse full text searching, you will need to install
  92. glimpse in /usr/bin.  Redhat rpm users can get glimpse from 
  93.  
  94.    ftp://ftp.redhat.com/pub/non-free/glimpse-3.0-1.i386.rpm
  95.  
  96. The glimpse home ftp site is cs.arizona.edu.  N.B. glimpse is not
  97. freely redistributable for commercial use, I'd be very interested in a
  98. more liberal alternative.  Having installed glimpse, you will need to
  99. build a glimpse index in /var/man2html.  This doesn't take too long -
  100. about 3 minutes on my 486DX2/66 16MB machine.  As root do:
  101.  
  102.    /usr/bin/glimpseindex -H /var/man2html /usr/man/man* /usr/X11R6/man/man* \
  103.       /usr/local/man/man* /opt/man/man*
  104.    chmod +r /var/man2html/.glimpse*
  105.  
  106. This could be set up as a cron job in /etc/crontab, e.g. (the following
  107. must be all on one line):
  108.  
  109.    21 04 * * 1 root /usr/bin/glimpseindex -H /var/man2html /usr/man/man* 
  110.        /usr/X11R6/man/man* /usr/local/man/man* /opt/man/man* ;
  111.        chmod +r /var/man2html/.glimpse*
  112.  
  113. If you don't want to use glimpse you can edit the man.html file that 
  114. the package installs in /home/http/html/man.html, and remove the 
  115. references to full text searches and glimpse.  This file can also be
  116. edited to include any local instructions you might wish to include.
  117.  
  118. The scripts may generate errors to the httpd error log
  119. /var/log/httpd/error_log.  The man binary (used to obtain the man-path
  120. by some of the scripts) seems to always think it's talking to a tty,
  121. and tries to obtain the screen size, resulting in the following error
  122. log entries:
  123.  
  124.   TIOCGWINSZ
  125.   failed : Bad file number
  126.  
  127. To serve man pages to remote hosts, all that is required is a httpd 
  128. daemon that sets the environment variable SERVER_NAME correctly.
  129.  
  130. END OF QUICK START INSTRUCTIONS
  131. -------------------------------
  132.  
  133. Vh-man2html was was written by Richard Verhoeven (NL:5482ZX35) at
  134. the Eindhoven University of Technology (Email: rcb5@win.tue.nl).  The
  135. original source is available from his web page at:
  136.  
  137.     http://wsinwp01.win.tue.nl:1234/maninfo.html
  138.  
  139. There are other man2html programs around - Richard's page has links to
  140. several of them.  Richard's man2html has some useful features for
  141. Caldera/RedHat Linux -
  142.  
  143.   Works from the troff/nroff source pages.
  144.     With linux we almost always have the man source.
  145.     Doesn't have to run man+tbl+eqn+nroff to generate output.
  146.     Because man isn't run, no catman pages are generated.
  147.     Accurate - doesn't have to guess from the man output.
  148.     Does tables (eg man ascii) (but doesn't do eqn - few pages use eqn).
  149.   Written in C - efficient speed/memory usage.
  150.     Fast enough not to need a cache.
  151.   Intelligent 
  152.     Makes good guesses on where to find pages.
  153.     Creates links for man pages and include files.
  154.  
  155. Richard's original program copes with pages formatted with the man
  156. macros.  I've enhanced it by adding translations for the mandoc macros
  157. used in the BSD man pages.  BSD mandoc pages in Caldera/Redhat
  158. include Mail, ftp, telnet, rlogin, and lpr and other printer man
  159. pages - so they're pretty important.  
  160.  
  161. I don't have any documentation on the mandoc macros, so I've had to
  162. guess what they intend, by looking at man source, man output and the
  163. gnroff macro definitions.  I've tested it on all the BSD mandoc pages
  164. in Section 1 that I could find.  It works reasonable well.  There are
  165. still minor formatting glitches to do with punctuation placement.
  166. I checked the BSD mandoc with weblint, e.g. in tcsh/csh
  167.  
  168.   foreach i ( `egrep -l '^\.Bl' /usr/man/man1/* /usr/man/man8/*` )
  169.       /home/httpd/cgi-bin/man2html $i > tmp/`basename $i`
  170.   end
  171.   weblint tmp/*
  172.  
  173. For broader testing:
  174.  find /usr/man/man* -name '*.[0-9]' \
  175.  -printf "echo %p; /home/httpd/cgi-bin/man2html %p | weblint -x netscape -\n" \
  176.  | sh \
  177.  |& tee weblint.log
  178.  
  179. If you want to sample the spectrum of mandoc translation, look at
  180. any of the pages the above grep locates, telnet, lpc, and mail
  181. are good examples.
  182.  
  183. As well as the mandoc modifications, I've also modified and configured
  184. man2html for Caldera/RedHat, and I've made the code a little more
  185. robust (for full details see the patch included in the source
  186. archive).  I've added index cgi scripts and a "main" html page.  The C
  187. source has been modified to link generated html man pages back to the
  188. "main" page.
  189.  
  190. Here's a summary of the rpm's components:
  191.  
  192.   1)  man.html       - Main page or access to man2html and man indexes.
  193.   2)  man2html       - CGI binary that converts man pages to html.
  194.   3)  manwhatis      - CGI script for a name and synopsis index organised
  195.                        by manual section
  196.   4)  mansec         - CGI script for a name only index for each section.
  197.   5)  mansearch      - Glimpse full text searching.
  198.   6)  mansearch.html - Main page or access to man2html and man indexes.
  199.   7)  /var/ma2html   - Cache directory for indexes and glimpse indexes.
  200.  
  201. All my scripts are written in awk.  In detail...
  202.  
  203. The manwhatis script creates section contents html files by looking
  204. for whatis files along the man path.  Each whatis entry is translated
  205. to a man2html link.  Manwhatis caches it's output in
  206. /var/man2html/whatis-[0-9].html.  The cache will be regenerated if any
  207. whatis file in the man path is updated (eg touch /usr/man/whatis).
  208.  
  209. The mansec script lists the names of all manual pages for a given
  210. section by using find on the man path.  It caches its output in
  211. /var/man2html/manindex-[0-9].html.  The cache will be regenerated if
  212. any associated man[0-9] directory in the man path is updated.
  213.  
  214. The mansearch script uses glimpse to get back a list of files and
  215. matches which it links back to the actual man pages.  The mansearch
  216. script is not pure awk.  It's starts out as a shell script to ensure
  217. that the parameters are safely passed to awk.  I think it's secure,
  218. but I'm not a cgi script expert.
  219.  
  220. To build and install man2html, the scripts, and man.html from the
  221. source archive. 
  222.  
  223.   make install
  224.  
  225. To build binary and source rpms, placing them under /usr/src/...
  226.  
  227.   make rpm
  228.  
  229. ---------------
  230. Patch to makewhatis from man-1.4g so that makewhatis will produce 
  231. full section details: e.g. xterm(1x) rather than xterm(1).  Put the
  232. patch in a file and enter:
  233.           cd /usr/sbin
  234.           patch < thepatchfile
  235.  
  236. --- cut here ---
  237. --- man-1.4g/src/makewhatis.sh  Tue Apr  2 10:51:14 1996
  238. +++ makewhatis                  Mon Apr  8 17:54:47 1996
  239. @@ -157,6 +157,12 @@
  240.                           filename ~ /\.gz$/);
  241.               match(filename, "/[^/]+$");
  242.               progname = substr(filename, RSTART + 1, RLENGTH);
  243. +             if (match(progname, "\." section "[A-Za-z]*")) {
  244. +               actual_section = substr(progname, RSTART + 1, RLENGTH);
  245. +             }
  246. +             else {
  247. +               actual_section = section;
  248. +             }
  249.               sub(/\..*/, "", progname);
  250.               if (use_zcat) {
  251.                 pipe_cmd = "zcat " filename;
  252. @@ -246,7 +252,7 @@
  253.                               where = 0;
  254.                             }
  255.                             printf "%-*s", 20-charct, sprintf( "%s (%s)",
  256. -                           substr( $0, 0, where-1 ), section );
  257. +                           substr( $0, 0, where-1 ), actual_section );
  258.                             printf "%s", substr( $0, where )
  259.                             if ($0 ~ /- *$/) {
  260.                               needmore = 1;
  261. --- cut here ---
  262.  
  263. ---------------
  264.  
  265. My modifications, packaging and scripts are copyright (c) 1996 
  266. Michael Hamilton (michael@actrix.gen.nz).  All rights reserved.
  267.  
  268. Permission is hereby granted, without written agreement and without
  269. license or royalty fees, to use, copy, modify, and distribute this
  270. software and its documentation for any purpose, provided that the
  271. above copyright notice and the following two paragraphs appear in all
  272. copies of this software.
  273.  
  274. IN NO EVENT SHALL MICHAEL HAMILTON BE LIABLE TO ANY PARTY FOR DIRECT,
  275. INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
  276. THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF MICHAEL
  277. HAMILTON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  278.  
  279. MICHAEL HAMILTON SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  280. BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  281. FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  282. ON AN "AS IS" BASIS, AND MICHAEL HAMILTON HAS NO OBLIGATION TO
  283. PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  284.  
  285.  
  286. Michael
  287.